BBS in a Box 15/BBS in a box XV-2.iso/Files II/Newton/Books/Make NB5.sit/MAKE NB5/COMPILE.TXT

Text File | 1994-01-05 | 17.8 KB | 451 lines | [TEXT/MSWD]

How To Make NewtonBooks, Part Five - Compiling Your Books

January 5, 1994
Copyright (c) 1994 Tony Lindsey, ([e-mail]). The
articles in this series may be copied freely, but may not be
sold unless prior permission is obtained.

PREREQUISITES FOR THIS ARTICLE

I expect that you have downloaded the previous articles in
the How2MakeNewtonBooks series. If not, please refer to the
README.5TH file enclosed with this document to find out
where they can be found.

This is part of an ongoing series of articles. A clever person
following this series should be able to use these articles to
create simple books that can be read on a Newton MessagePad
or other product with Newton Intelligence.

I will be assuming that you are attempting the following steps
on a Macintosh computer, IIcx or later, with a minimum of 8
megabytes of RAM, running System 7.1.. I also assume that
you have Newton ToolKit version 1.0b7 and Newton Book
Maker 1.0b7.

MAKING SURE ALL OF THE PARTS ARE IN PLACE

First, I will review the proper location of Newton ToolKit (NTK)
components.  The following instructions apply to version
1.0b7, and the instructions may change without notice.  You're
on your own, in that case.

There are parts scattered in various locations, and you may
not get predictable results if all of the pieces are not present
and accounted for.

If NTK is properly installed, then the System Folder should
have the following files in the following locations:

IN THE FONTS FOLDER (USING SYSTEM 7.1 or later):

There should be a suitcase called Newton ToolKit Font.  It's not
strictly required for our BookMaking tasks.

IN THE EXTENSIONS FOLDER:

There should be two files that are needed:

- Apple Modem Tool (version 1.5 should work file, but slightly
older versions seem to work fine as well).

- AppleTalk ADSP Tool (version 1.01 is satisfactory)

I believe that these are only needed if you are planning to
transfer the completed books over an AppleTalk connection.

THE CLARIS FOLDER

This is a very important folder within your System Folder.
BookMaker needs this folder and its contents to read in word-
processor files and interpret their commands for font and
style changes.

Claris (a subsidiary company of Apple Computer) created a
system that provides a standardized method of reading and
translating files that were created by completely different
programs.  The Claris folder is provided free with programs
such as FileMaker, MacWrite and Claris Works.

The Claris folder should contain the following items:

- Claris XTND System (version 1.3.6 is nice), and

- A folder called Claris Translators.

THE CLARIS TRANSLATORS FOLDER

This folder should contain files with names like these:

MacPaint
MacWrite
Microsoft Word 3.0
Microsoft Word 4-5
Microsoft Word PC 4.0-5.0
Microsoft Works 1.1
Microsoft Works 2.0
Microsoft Works DB
PICT
TIFF
WordPerfect

These are the files that allow documents to be recognized and
translated by BookMaker or any other program that uses the
Claris XTND system.

THE REMAINING FILES

Newton ToolKit comes with scads of freebie files that are used
to demonstrate and illuminate the glory of creating your own
programs.  I will ignore these demo files in my article, and will
only mention the components required for compiling books:

- Newton Toolkit (version 1.0b7 or later)

- Newton Book Maker (version .0b7 or later)

- a folder called "Platforms"

THE PLATFORMS FOLDER

This folder may contain a single file:

- MessagePad (no version given)

Or, as technology advances, and as more models of the Newton
arrive with different-size screens, each one should have its
own, appropriately-named file in the Platforms folder.  I am
guessing that this folder contains "cheat sheets" that inform
NTK what size and resolution a Newton's screen may have.

MODIFICATIONS TO THE NEWTON TOOLKIT 1.0B7 PROGRAM

Before we continue, it might be a good idea to check to see
what version of NTK we are using.  Click once on the Newton
ToolKit program and choose "Get Info" under the File menu.  It
might say Version: 1.0b7 (the seventh beta version of NTK).
Later versions (such as 1.0) should not need the following bug
fix.

BIG BOOK BUG FIX

Here's how the bug shows up: when compiling a long book
(over about 300 pages, or about 200k in size), NTK runs out of
"FrameStorage Heap" or some such thing, and suggests we
increase it.  Increasing memory to NTK does not solve this,
because it still stops at the same place, refusing to proceed.

This one has an easy answer:

- Make a backup copy of Newton ToolKit

- Open NTK with ResEdit

- Hit the letter "H" on your keyboard.  This highlights the
"HEAP resource icon.

- double-click on the HEAP icon.  You'll see two choices.

- double-click on each one, change its number to 2048, and
close its window.

- Quit from ResEdit.  When asked if you want to save changes,
choose "Yes"

You should see no adverse effects.  You are on your own.

COMPILING YOUR BOOK

Here is every step used to compile NewtonBooks.  I am
assuming that you have the final "GRANGE.DOC" file I included
in the first collection of files in the How2MakeNewtonBooks
series.  I will use it in the following example:

- Drag the fully-formatted MS Word file called "GRANGE.DOC"
into BookMaker, and then click on the "Do it" button.

-Wait awhile, then when offered the chance to save a file, click
on the Desktop button and save the default filename.  This
file's name should automatically end with ".f"  This creates an
"intermediate" file, which can be thrown away later when the
package-making process is complete.  Example: "GRANGE.DOC.f"

- Wait some more, and when the watch cursor disappears, quit
BookMaker and then begin using Newton ToolKit.

- When offered the chance to open an existing file, click Cancel.

- Under the Project menu, choose "New Project"

- Click on Desktop, and give the new file an appropriate name
that ends with a .PRJ (shorthand for Project, and totally
unnecessary, but it helps distinguish among many files).
(Example: GRANGE.PRJ) This creates yet another "intermediate"
file that we will be throwing away later.

- Under the Project menu, choose Add Book File.  Double-click
on the filename that ends with ".f"  This adds the only file we
need for this project.

- Under the Project menu, choose "Package Settings"

- In the middle of the dialog box, you'll see "ChangeMe:Sig"
This is where you are supposed to identify the package as well
as yourself.  The information you put here is what shows up in
the "Remove Software" dialog on your Newton. The part that
says "ChangeMe" should contain a nice, short version of the
book's name.  Try to keep it under nine characters.  In the
example of "The Adventure of the Abbey Grange", I chose to
use "Grange"

Apple has a registry of programmer's identifiers that go where
the word "Sig" goes. For this example, the folks helping me
with my many, many books would put "Grange:NewtBoy"
NewtBoy is just a distinctive name I chose.

- Click on "OK".  There are other settings that could be changed,
but they are outside of the purpose of this article, which is to
make a book with as few steps as possible.

- The final step:  Under "Project", choose "Build Package" and
then wait for the watch cursor to go away.

- Quit from NTK.

After that, do some cleanup... Throw away the GRANGE.f and
GRANGE.PRJ files, and tidy up around the place.  You should
find a file called GRANGE.PROJ.PKG in the same location.  That's
your book!

- Rename the book to adhere to the PC world's file-naming
conventions.  There should be a maximum of 8 characters
before the period. In this case, it would be called
"GRANGE.PKG."  I specify renaming it this way because I
assume that you want to share your new book with as many
folks as possible.  According to a recent MacWeek magazine
article, 40% of all Newton owners use an IBM-compatible
computer.

WHAT TO DO WITH YOUR PACKAGE FILE

Of course, the first thing you'll want to do is load it onto your
Newton. There are several ways of doing so.  I've found that
the simplest way is to use the program called "Package
Express" that comes with Newton ToolKit.

- Make sure that your Newton is correctly connected to the
Mac.  I personally have my Mac, my laser printer and my
Newton connected with three Farallon PhoneNet connectors.
This AppleTalk connection allows me to reserve my Phone
port for my modem.  I'm assuming that you have the same
setup.  If so, make sure that you have two terminating
resistors plugged into each end of your mini-network.  They
came free with the PhoneNet connectors.

- If all physical connections are made, turn on your Newton

- Tap on Extras

- Tap on Connection

- Make sure that "Macintosh LocalTalk" is selected

- Tap on "Choose Macintosh"

- On the Mac, drag GRANGE.PKG into Package Express's icon.
As soon as you see the striped bar moving in the dialog box,
grab the Newton.

- On the Newton, look to see if your Mac's name shows up as
highlighted text.  If so, tap on "Connect." If not, tap on "More
Choices", wait for your Mac's name to show up, and then tap
"Connect".  If NO name shows up, maybe you never got around
to naming your Mac.  To name your Mac, you need to quit
from Package Express, pull down the Apple menu, go to your
Control Panels, choose Sharing Setup, fill in the first and third
fields, close the window and then restart the Mac.  This tells
System 7 to start announcing itself on networks when asked to
by programs like Package Express. After restarting, try these
steps again.

- After tapping "Connect" you might see an error message on
the Mac.  This is utterly normal with the Package Express that
came with NTK 1.0b7.  Just hit the Return key on your
keyboard and the book should load just fine.  You could also
use Newton Connection Kit or Newton ToolKit to load the book
package, but this is the simplest technique.

CHECKING FOR FLAWS IN YOUR BOOK

Assuming that you have gotten this far successfully, you
should be able to tap on your Newton's Extras drawer icon.  I
am assuming that you have compiled the GRANGE.DOC file I
included with my first article in this series. I will now provide
a checklist of flaws to watch out for:

- You should see a book icon with a SHORT (maximum 10
characters) name beneath it.  If it's any longer, it won't be
readable when other packages have long names on either side.
This can be changed by modifying the .shortname dot
command in the GRANGE.DOC file and recompiling.

- Tap on your book's icon.  You should see an attractive title
page (with a nice picture of Sherlock Holmes if you're looking
at GRANGE.PKG).  There should be no tiny, bold title at the
extreme top line of the first page.  If there is, try adding the
"notitle" modifier to the title page's .layout command, like this:

.layout title 12 notitle

- Tap the Overview dot between the arrows at the bottom of
the Newton's screen.  You should see the book's title and the
"Publisher's Notes" if you are looking at GRANGE.PKG, or a nice
collection of chapter headings if you are reading a book with
chapters.

- Close the Overview drawer, and tap the down arrow to flip
through the book's pages. You should have no trouble reading
the text, due to tiny size or awkwardly-laid-out paragraphs.
The text should be easily readable.  I personally favor the 12-
point Fancy (New York) font.  It means more pages, but you
should never assume that everyone has eyesight as sharp as
yours.  There are a lot of aging Baby Boomers out there!

If possible, hand the book over to a friend for proofreading.
I admit I've neglected this step in the past.  After working on
a book for a long time, I hate to stare at it to look for flaws.
My eyes cross, and I want to go take a nap.  A friend will help
you spot stuff like "Sherlock Holrnes" , which is an actual typo
I missed the first time around.

- Check to see if there any text is italicized.  If so, take a good
look at how awful it appears.  Avoid it at all costs!  I know
that bold or underlined text is a poor substitute, but give it a
try.  Alternately, consider using the Simple (Geneva) font as a
final possibility.

- Paragraphs should have a blank line between them.  If you
leave these out, the text becomes uniform, with no visual
breaks for your eyes to distinguish where they are.  If you
glance away, the act of looking for your place again becomes a
chore.

- Check to make sure that chapters break up the text properly.
I have seen NewtonBooks that were never checked for this,
and the end of one chapter and the beginning of another didn't
look right, with blank pages or run-on text.

- Look for curly quotes and apostrophes.  They are optional,
but the details do count.  Look for double-hyphens.  They
should not exist, instead having been replaced by em-dashes.
The Newton has the design goodness to include these, so why
not use them?

I'm sure that there are many, many other things that could go
wrong with your books, but only you can spot them, since you
are the publisher of your own books.  Use your own standards,
but do your best!

WHY YOU SHOULD SHARE YOUR BOOK WITH THE WORLD

Let's say that your newest NewtonBook is a work of art.
You're proud of what you have done, and you want to share it
with as many folks as possible.  I have found America Online's
Palmtop Paperbacks section (Go to Keyword "PDA") to be the
largest library of NewtonBooks in existence as of this writing.

I would like to ask you to share your books because it helps
many, many more people than you could imagine.  Think of a
classroom full of kids in 1996, using the "Tom Sawyer" book
on their inexpensive slate computers.  The teacher would tap a
single button on a screen, and every child would get a copy of
the book at that moment.

I leave it up to YOU whether you want to ask for a shareware
fee, or keep the book as free as the breeze.  Personally, I'm
very idealistic, and have never asked for a fee for any of the
books I've created. I've been downloading texts from America
Online and other bulletin boards, and re-issuing them in
NewtonBook format.  I feel that it would be wrong for me to
take another person's work and charge for it.  Some day, I will
be writing my own books in NewtonBook format, and I haven't
yet figured out the way I'll merchandise them.

CREATING AN INFORMATION FILE

I have a lot of experience with uploading articles and other
creations.  They have a way of whisking out of your control in
ways that you would never expect.  People may download
your file long after you have forgotten about it, in places like
Singapore and the Ukraine.  I think of myself as a mother sea
turtle, who distributes her eggs and never sees them again.  If
this concept doesn't bother you, you should consider the needs
of the folks who get your document.

FILE NAMING CONSIDERATIONS

If you are willing to share the book you've created, you should
consider non-Mac Newton users.  They can't always deal with
long filenames with funny characters or spaces.  They also
need to acquire the book file in a compressed format that they
can decompress with no problems.

I always include an INFormation file with my books.  I also
compress the two files with Stuffit Deluxe.  I also might
include the original word-processing file I used to create the
book, just so beginners could study how I did it. You can see
an example of this on AOL in the "Nude Beaches of California"
file I uploaded.

When creating an INFormation file, I make sure it's a PC-
compatible ASCII text file with linefeeds.  I explained how to
do this at the end of FILTER.DOC, which is part of the
How2MakeNewtonBooks #3 article on AOL.  I also make sure it
has the same sort of name as the book.  For example, I would
have a book called "GRANGE.PKG", and an INFormation file
called "GRANGE.INF."

I would use Stuffit Deluxe to store the both of those files in an
archive called "GRANGE.SIT."  I like Stuffit Deluxe because it's
available on both the PC and Mac platforms, and America
Online will automatically decompress the files after
downloading.  Compressing the files saves money spent on
downloading time, and it keeps the appropriate files together.

Stuffit Deluxe is available from many mail-order and software
retailers.

Using Stuffit Deluxe, I would choose "New" under the File
menu, type in a filename like GRANGE.SIT, and then click on
the "Stuff" icon.  I would then double-click on GRANGE.PKG and
GRANGE.INF. and then click on the "Stuff" button.  After
quitting, I'm ready to upload the GRANGE.SIT file.

UPLOADING ONTO AMERICA ONLINE

I upload my files by following this procedure:

I sign on to AOL, and choose "Key word" under the "Go To"
menu.  Type "PDA" and hit return.  Click on "New Files & Free
Uploading" and click on the "Upload File" button, and fill out
the form.  If you're not sure how to phrase any of the words
you put in these fields, just copy what I've done with any of
my files like "Nude Beaches of California".

-------------

This concludes the first five installments of this series.  I have
tentatively planned a sixth article for some future date,
including a few corrections and additional tips.  I will also
make it my business to learn more dot commands.  I will be
uploading more-elegant books, but I will also enclose the
documents I used to create these books.  I hope that this will
encourage others to publish ever-nicer books.

I don't know what the future holds, but it is my fervent wish
to see massive numbers of books available for the people of
the world.  Let's all do our part!

Tony Lindsey, San Diego, California, Wednesday, January 5,
1994.